feat: add event enrichment client by thisisabhash · Pull Request #4243 · aws-amplify/amplify-swift

thisisabhash · 2026-07-01T18:59:31Z

Issue #

None

Description

Summary

Adds AmplifyEventEnrichmentClient — a standalone on-device event enrichment client that attaches device/app/session/identity context onto analytics events and produces a Pinpoint-compatible JSON envelope (v3.1).

This is the Swift counterpart to the Flutter amplify_event_enrichment_dart package (amplify-flutter#7029). It enables events sent via Kinesis/Firehose to retain the analytics context that Pinpoint previously provided automatically.

Key design points

Actor-based with full strict concurrency (Sendable everywhere)
Zero AWS SDK dependency — depends only on AmplifyFoundation; transport is delegated to the EventSink protocol
Automatic clientId resolution — persisted UUID via UserDefaults (key: com.amazonaws.amplify.event_enrichment.client_id) with read-or-create pattern, matching the Flutter SharedPreferencesClientIdProvider approach
Automatic lifecycle tracking — subscribes to platform NotificationCenter notifications (same approach as the Pinpoint plugin's ActivityTracker) to pause/resume sessions on background/foreground transitions
Device metadata aligned with Pinpoint plugin — uses UIDevice/WKInterfaceDevice/IOKit matching existing DeviceInfo patterns
Session timeout — configurable duration (default 5s) after which a backgrounded session expires and a new one starts on next foreground

Public API

Type	Role
`AmplifyEventEnrichmentClient`	Main actor — `record()`, session control, global fields, userId, close
`EnrichedEvent`	Immutable event model with `toJson()` → Pinpoint envelope
`Session`	Session model with `Date` timestamps + duration
`EventSink` (protocol)	Transport abstraction (Kinesis, Firehose, custom)
`EventEnrichmentClientOptions`	Config: `autoSessionTracking`, `sessionTimeout`
`EventEnrichmentError`	`AmplifyError`-conforming error enum
`AppMetadata` / `DeviceMetadata` / `SDKMetadata`	Metadata value types

Files

14 source files in AmplifyClients/AmplifyEventEnrichmentClient/Sources/
5 test files with 27 unit tests covering: recording, global fields, session lifecycle, timeout, JSON serialization, event sink, activity tracker integration
Package.swift — new target + product added

Test plan

swift build --target AmplifyEventEnrichmentClient compiles cleanly
swift test --filter AmplifyEventEnrichmentClientTests — 27 tests pass
Verify JSON output matches Pinpoint event ingestion format
Integration test with AmplifyKinesisClient or AmplifyFirehoseClient as an EventSink
Test on iOS device to verify lifecycle notifications fire correctly
Test on macOS to verify NSApplication notification path

General Checklist

Added new tests to cover change, if needed
Build succeeds with all target using Swift Package Manager
All unit tests pass
All integration tests pass
Security oriented best practices and standards are followed (e.g. using input sanitization, principle of least privilege, etc)
Documentation update for the change if required
PR title conforms to conventional commit style
New or updated tests include Given When Then inline code documentation and are named accordingly testThing_condition_expectation()
If breaking change, documentation/changelog update with migration instructions

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

codecov · 2026-07-02T20:03:23Z

Codecov Report

❌ Patch coverage is 88.98305% with 39 lines in your changes missing coverage. Please review.
✅ Project coverage is 66.95%. Comparing base (48f97ce) to head (254a947).
⚠️ Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
...tClient/Sources/Support/EventEnrichmentError.swift	0.00%	23 Missing ⚠️
...richmentClient/Sources/Support/EnrichedEvent.swift	86.15%	9 Missing ⚠️
...lient/Sources/Support/DeviceMetadataProvider.swift	73.91%	6 Missing ⚠️
...ichmentClient/Sources/Support/SessionManager.swift	98.71%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4243      +/-   ##
==========================================
+ Coverage   66.80%   66.95%   +0.15%     
==========================================
  Files        1157     1170      +13     
  Lines       44185    44539     +354     
==========================================
+ Hits        29517    29823     +306     
- Misses      14668    14716      +48

Flag	Coverage Δ
API_plugin_unit_test	`68.16% <ø> (-0.18%)`	⬇️
AWSPluginsCore	`68.07% <ø> (ø)`
Amplify	`47.47% <ø> (ø)`
Amplify_Foundation_Bridge_unit_test	`62.28% <ø> (ø)`
Amplify_Foundation_unit_test	`67.64% <ø> (ø)`
Analytics_plugin_unit_test	`83.43% <ø> (ø)`
Auth_plugin_unit_test	`72.47% <ø> (-0.03%)`	⬇️
Connect_unit_test	`42.95% <ø> (ø)`
DataStore_plugin_unit_test	`82.81% <ø> (+0.01%)`	⬆️
EventEnrichment_unit_test	`88.98% <88.98%> (?)`
Firehose_plugin_unit_test	`53.15% <ø> (ø)`
Geo_plugin_unit_test	`73.39% <ø> (ø)`
Kinesis_plugin_unit_test	`52.17% <ø> (ø)`
Logging_plugin_unit_test	`64.86% <ø> (ø)`
Predictions_plugin_unit_test	`34.09% <ø> (ø)`
PushNotifications_plugin_unit_test	`84.58% <ø> (ø)`
RecordCache_unit_test	`76.40% <ø> (ø)`
Storage_plugin_unit_test	`78.67% <ø> (ø)`
unit_tests	`66.95% <88.98%> (+0.15%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

cadivus

I have one nit, the rest looks good.

ekjotmultani · 2026-07-15T21:56:30Z

One cross platform consistency item that still stands after the recent fixes: the client id is persisted under com.amazonaws.amplify.event_enrichment.client_id, but the other platforms settled on a single shared key, com.amplifyframework.device_id, stored in plain UserDefaults. The Connect client will read the same key so that enrichment and Connect report the same stable device id for a given install. As written the two Swift packages would generate different ids. Could we switch the key here so the contract holds on Swift too?

thisisabhash had a problem deploying to IntegrationTest July 1, 2026 18:59 — with GitHub Actions Error

thisisabhash temporarily deployed to Fortify July 1, 2026 19:11 — with GitHub Actions Inactive

thisisabhash temporarily deployed to IntegrationTest July 1, 2026 19:11 — with GitHub Actions Inactive

cadivus reviewed Jul 2, 2026

View reviewed changes

cadivus reviewed Jul 7, 2026

View reviewed changes

Comment thread AmplifyClients/AmplifyEventEnrichmentClient/Sources/AmplifyEventEnrichmentClient.swift Outdated

cadivus previously approved these changes Jul 7, 2026

View reviewed changes

harsh62 reviewed Jul 28, 2026

View reviewed changes

Comment thread AmplifyClients/AmplifyEventEnrichmentClient/Sources/Support/DeviceMetadataProvider.swift

Comment thread AmplifyClients/AmplifyEventEnrichmentClient/Sources/Support/DeviceMetadataProvider.swift

harsh62 previously approved these changes Jul 28, 2026

View reviewed changes

ekjotmultani previously approved these changes Jul 29, 2026

View reviewed changes

thisisabhash added 11 commits July 31, 2026 13:49

feat: add event enrichment client

2df1961

add more tests

c050174

fix swiftformat issue and run tests on CI/CD

9ba8edf

add appId to client init and persist client id internally

e253d2e

address review comments

090791b

add missing test scheme

772512c

update tests

099f78e

address review comments

4b10886

address review comment

3521eb9

address review comments

2754459

address review changes

254a947

ekjotmultani approved these changes Aug 3, 2026

View reviewed changes

This was referenced Aug 5, 2026

Merge upstream aws-amplify/amplify-swift main (through 2.60.1) paywithextend/amplify-swift#4

Closed

Merge upstream aws-amplify/amplify-swift main (through 2.60.1) paywithextend/amplify-swift#5

Merged

Navigation Menu

Uh oh!

feat: add event enrichment client - #4243

feat: add event enrichment client#4243
thisisabhash merged 11 commits into
mainfrom
feat/event-enrichment-client

thisisabhash commented Jul 1, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

codecov Bot commented Jul 2, 2026 •

edited

Loading

Uh oh!

Uh oh!

cadivus left a comment

Uh oh!

ekjotmultani commented Jul 15, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

thisisabhash commented Jul 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Issue #

Description

Summary

Key design points

Public API

Files

Test plan

General Checklist

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

codecov Bot commented Jul 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

cadivus left a comment

Choose a reason for hiding this comment

Uh oh!

ekjotmultani commented Jul 15, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

thisisabhash commented Jul 1, 2026 •

edited

Loading

codecov Bot commented Jul 2, 2026 •

edited

Loading